# Copyright (C) 2007 Richard Boulton
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
r"""errors.py: Error handling routines.

"""
import cgi

class SFeedError(Exception):
    """Base class of all exceptions raised by SFeed.

    """
    pass

class UserError(SFeedError):
    """An error which should be displayed to users.

    The constructor takes a format parameter and some arguments.  Any special
    HTML characters in the arguments (but not in the format parameter) are
    escaped, so the resulting message can be safely displayed in a browser (as
    long as the format parameter is sensibly written).

    """
    def __init__(self, format, *args):
        escaped_args = []
        for arg in args:
            if isinstance(arg, str):
                arg = str.decode('utf-8')
            if isinstance(arg, unicode):
                arg = cgi.escape(arg)
            elif isinstance(arg, (int, long, float)):
                pass
            else:
                arg = unicode(arg)
            escaped_args.append(arg)
        SFeedError.__init__(self, format % escaped_args)

class AdminError(SFeedError):
    """An error which should be displayed to administrators.

    """
    pass

class DatabaseVersionTooOld(AdminError):
    """An error which indicates that the existing database version is out of
    date, and there is no automatic upgrade script known.

    This either indicates that the Database is too old to upgrade, or possibly
    that the old database version was never officially released, so no upgrade
    path was implemented.

    In either case, the usual resolution is to downgrade the software to an
    earlier version which supports the database version, or to remove the
    database entirely and start again from scratch.

    """
    pass

class DatabaseVersionTooNew(AdminError):
    """An error which indicates that the existing database version was produced
    by a newer version of the software, and we don't know how to read it.

    The usual resolution is to upgrade the software to a new version which
    supports the database version, or to remove the database entirely and start
    again from scratch.

    """
    pass
